docusaurusで遊ぶ
概要
Autoyaのドキュメントの既存資産部分をプレゼンテーションスタイルからちゃんとしたドキュメントに移動する、というのをずっとやっていた。
んで目処が立ったんで最新化も行うなど。去年末くらいから開始して結構かかったな、、、
使っているもの
docusaurus
目次があるドキュメントツールが欲しかったので選んだ。
インストール
いろんなところに書いてあるんではい。公式。
https://docusaurus.io/docs/en/installation.html
構造的な概要
つぎのようなファイルを基礎に成立している。フォルダ名は鬱陶しいのでverifyを終えた時のものに合わせてある。
⁃ markdownで書かれたexampleなドキュメンテーション記事置き場
サイト構築に際して
簡単なページを作ってみる。
条件として、
・ファイル名と内部で記述するidが一致すること
・必ずヘッダーパラメータを入れること
などがある。
ヘッダーパラメータは次のようなもので、
---// このへんから
id: install0
title: Install Autoya to your project
sidebar_label: Installation
---// このへんまで
リリースにUnitypackageファイルがあるんで、その辺を選んで使うと楽。
idはファイル名に一致したもの、
titleはmdとは無関係に一番上に出る文字列、
sidebar_labelは、[この名前のsidebarの下にぶら下がる]という宣言になっている。
sidebar_labelがないと、そのページを表示する際にはサイドバーがないページが出てくる。
サイドバーをいじる
サイドバーはjsonになっている。
website/sidebars.json をいじることで編集できる。
こんな感じ。
{
"docs": {
"Getting started":["install0"],
"API":["api0"]
},
"docs-other": {
"First Category": ["doc4", "doc5"]
}
}
各ページのidを記述することで、簡単に目次が作れて便利。
docs-otherは表示されないっぽい。
サイドバーからコンテンツへとジャンプ、
コンテンツ間はコンテンツ間でリンク、
コンテンツにsidebarの表記がなければページ上もサイドバーが出ない、
みたいな挙動になっている。
サイドバー、概念的には
・一番大雑把な特性で所属をわける
Document、API、他、みたいな。
・Docはこのサイドバー、APIはこのサイドバー、みたいな概念ではない
ないっぽい。複数サイドバーみたいなissueが上がってそうな気はするが。
・サイト内で複数種類のサイドバーをせっていすることが可能。
こんな感じにした。
sidebars.json
{
"docs": {
"Installation": ["install0"],
"Overview": ["overview0", "overridepoints0"],
"Documents": [
"auth0",
"manifest0",
"persistence0",
"assetbundle0",
"connection0",
"maintenance0",
"purchase0",
"notification0",
"information0",
"settings0"
],
"Resource Management":[
"resource_generate0",
"resource_deploy0"
],
"App Management": [
"update_app_version0",
"update_resource_version0",
"turn_on_maintenance0"
]
},
"api":{
"APIs": [
"api_auth0",
"api_manifest0",
"api_persistence0",
"api_assetbundle0",
"api_http0", "api_udp0",
"api_maintenance0",
"api_purchase0",
"api_information0"
]
}
}
これで、docsとapiというサイドバーが作れる。
この名称はサイト上には一切現れないため、単に区別のためだけにある感じ。
ビルド
websiteフォルダー下で
yarn run build
とかやると、ビルドされる。
website/buildとかフォルダが生成される。
github pages向けだと、次のコマンドがあり、
yarn docusaurus-publish
できた中身をgithub pagesに関連づければよさげ。
Tips
blogは、yyyy-mm-dd-ファイル名.md でないとダメだとか。
Question
ライブリロードどうなってんの
https://github.com/facebook/Docusaurus/issues/234
-> 中にexpressが入ってるんで頑張ればできそうなんだけど、今のとこ無理。
mdで書くドキュメント類は単に更新すればhtmlに変換されて良いのだけれど、sidebarとかfooterの内容はコンパイルが必要なのか更新されない。
自分はyarn run startをした状態で別ターミナルで yarn run build とかでしのいでいる。
このへんはwatchで自動化すると良さそう。
docsの下にフォルダ掘りたいんだけどできないものか
https://github.com/facebook/Docusaurus/issues/323
-> 書き換えられるけどできない。flattenみたいなのを使う必要がある。
en から他の言語への切り替え
デフォルトを日本語で書いている(enなんだけどね)
https://docusaurus.io/docs/en/translation.html
-> まだ見てない。
検索窓
なんか有効にできるっぽい。
https://docusaurus.io/docs/en/search.html
-> まだ見てない。
やったことあるひといた。
http://efcl.info/2017/12/26/docusaurus-almin/